import { ExampleCode } from 'components/example-code'
import { Steps } from 'nextra/components'
import OldDocs from './old.mdx'

# Custom Theme

A theme in Nextra works like a layout, that will be rendered as a wrapper for
all pages. This docs will walk you through the process of creating a custom
theme.

> [!NOTE]
>
> Source code for the following custom theme can be found
> [here](https://github.com/shuding/nextra/tree/main/examples/custom-theme).

## Create a custom theme

<Steps>
### Create a root layout

<ExampleCode example="custom-theme" filePath="app/layout.tsx" />

### Create [`mdx-components` file](/docs/file-conventions/mdx-components-file)

<ExampleCode
  example="custom-theme"
  filePath="mdx-components.jsx"
  metadata="/toc/2 {9}"
/>
<ExampleCode
  example="custom-theme"
  filePath="app/_components/toc.tsx"
  metadata="/toc/"
/>

### Create a basic theme

You can now start working on your theme! Create the `nextra-theme.tsx` file, it
accepts a `children` prop, which is the MDX content of the current page, and
wraps some other elements around the content:

<ExampleCode
  example="custom-theme"
  filePath="app/_components/nextra-theme.tsx"
  metadata="/children/"
/>

### Create navbar and footer

<ExampleCode example="custom-theme" filePath="app/_components/footer.tsx" />
<ExampleCode
  example="custom-theme"
  filePath="app/_components/navbar.tsx"
  metadata="/topLevelNavbarItems/"
/>

### Create sidebar

<ExampleCode
  example="custom-theme"
  filePath="app/_components/sidebar.tsx"
  metadata="/docsDirectories/"
/>

### Add first MDX page

After creating the theme, you can simply add a MDX file as `app/page.mdx` and
see the result:

![Custom theme](/assets/docs/custom-theme.png)

<br />

Inside your theme layout, you can use CSS imports or other ways to style it.
Next.js hooks such as `usePathname` are also available.

{process.env.NODE_ENV !== 'production' && <OldDocs />}

</Steps>
